NDTS-GUI: Difference between revisions

From Network for Advanced NMR
Jump to navigationJump to search
← Older edit
VisualWikitext
No edit summary
No edit summary
 
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{NDTS_Navbox}}
== Overview ==
== Overview ==
NDTS installations on the spectrometer workstation are comprised of the daemon which runs as a service and the NDTS graphical user interface (NDTS-GUI) which provides status information and allows users to make changes to harvesting status, NAN user, and metadata that will be associated with datasets. NDTS is designed to automatically harvest datasets as they complete when harvesting is set to "on", but datasets can also be manually harvested through the NDTS-GUI.
NDTS installations on the spectrometer workstation consist of the daemon, which runs as a service, and the NDTS graphical user interface (NDTS-GUI), which displays status information and allows users to adjust harvesting status, select the NAN user, and provide metadata to be associated with datasets. NDTS is designed to automatically harvest datasets upon completion when harvesting is enabled. Manual harvesting can also be performed via the NDTS-GUI.
 
'''Important Note: For TopSpin 4.x and VNMRj the daemon will automatically detect when experiments are complete, but for TopSpin < 4.x each user must enable Accounting from their TopSpin account for the daemon to recognize when experiments complete'''
 
'''[[Enabling TopSpin Accounting|Instructions for turning on Accounting for TopSpin < 4.0]]'''


== Mapping NAN users to spectrometer workstation users ==
== Mapping NAN users to spectrometer workstation users ==
Datasets harvested need to be associated with a NAN user to allow the datasets to be visible from the Dataset Browser. This is primarily done through the NDTS-GUI where the NAN user may be changed (if the facility manager settings permit the action). By default the NAN user mapped to the spectrometer workstation is selected. The mapping is controlled by the NMR facility manager through a user management page on the NAN portal facility dashboard.
Each harvested dataset must be associated with a NAN user to be visible in the Dataset Browser. This association is managed primarily through the NDTS-GUI, where the selected NAN user can be changed (if permitted by facility manager settings). By default, the NAN user mapped to the current spectrometer workstation user is selected. These mappings are managed by the NMR facility manager through the user management page on the NAN portal Facility Dashboard.


== NDTS harvesting defaults ==
== NDTS harvesting defaults ==
From the Facility Dashboard facility managers use the Manage Facility Users tool to add NAN users to their facility, map those users to spectrometer workstation accounts, set default harvesting settings, and decide how to handle cases where the spectrometer workstation user is not mapped to a NAN user.
Facility managers use the ''Manage Facility Users'' tool on the Facility Dashboard to:
* Add NAN users to the facility
* Map users to spectrometer workstation accounts
* Set default harvesting preferences
* Define fallback behavior for unmapped users


When the NDTS-GUI is launched, or when the NAN user selected within the NDTS-GUI is changed, the default settings defined in the Manage Facility Users tool on the NAN web portal are refreshed to the default settings.
When the NDTS-GUI is launched or when the selected NAN user is changed, the default harvesting settings are refreshed based on the configuration in the *Manage Facility Users* tool.


If the NDTS-GUI is not running, than NDTS harvesting falls back to the default settings defined in the Manage Facility Users tool
If the NDTS-GUI is not running, NDTS harvesting defaults to the fallback settings defined in the ''Manage Facility Users'' tool.


== Launching the NDTS-GUI ==
== Launching the NDTS-GUI ==
As the harvesting settings will default to the settings defined in the Manage Facility Users tool it is important that the NDTS-GUI is running at all times so that the harvesting status is visible, and users have the ability to make changes before data collection to ensure proper harvesting and metadata. For this reason, once started the NDTS-GUI has the close button disabled to avoid accidental closing of the application. Users should also setup the NDTS GUI to launch automatically when logging in graphically to the spectrometer workstation.  
It is essential that the NDTS-GUI remain running so that harvesting status is visible and users can ensure appropriate metadata and settings are applied before data collection. To prevent accidental closure, the close button in the GUI is disabled once launched. It is strongly recommended to configure the NDTS-GUI to start automatically upon login to the spectrometer workstation.
 
=== Manually launching the NDTS-GUI ===
While automatic launching is preferred, the GUI can be started manually with:


=== Manually launch the NDTS-GUI ===
<code>/opt/nan-dtdaemon/nan_gui</code>
While it is better to automatically launch the NAN-GUI upon login, it may be launched manually with the command


<code>/opt/nan-dtdaemon/nan_gui</code>
=== Automatically launching the NDTS-GUI ===
The setup depends on the desktop environment and whether the configuration is per-user or system-wide. Below are instructions for different desktop environments, but with so many different versions and different Linux distros it is impossible to cover all possibilities. That said, launching an applications upon login is a common task as the correct answer can usually be found easily with a Google search or by asking one of the LLMs such as ChatGPT.


=== Automatically Launch the NAN-GUI ===
==== Step 1: Identifying the desktop environment ====
The exact procedure will depend on which desktop environment you are using and whether you are setting up automatic launching for a single user account or as a system-wide setting for all users.
Use this command to determine your current desktop environment


==== Checking which desktop environment you are using ====
<code>echo $XDG_CURRENT_DESKTOP</code>  
<code>echo $XDG_CURRENT_DESKTOP</code>  


or  
if the above command does not work or show output try:


<code>echo $DESKTOP_SESSION</code>
<code>echo $DESKTOP_SESSION</code>


==== Creating the launcher script ====
==== Step 2: Creating the launcher script (if adding from the CLI) ====
<syntaxhighlight lang="ini">
If you are adding the launcher script through the command line interface you will need to create the text file below using your favorite editor and save it to the appropriate location (see the table below of the CLI-based path)<syntaxhighlight lang="ini">
[Desktop Entry]
[Desktop Entry]
Type=Application
Type=Application
Line 40: Line 52:
Comment=NDTS graphical interface
Comment=NDTS graphical interface
X-GNOME-Autostart-enabled=true
X-GNOME-Autostart-enabled=true
</syntaxhighlight>Make it executable:
</syntaxhighlight>Most Linux distros also have the ability to add a launcher through the menu bar. Below in the table follow the directions for the Menu-Based instructions to add the launcher and select <code>/opt/nan-dtdaemon/nan_gui</code> as the program to launch
 
<code>chmod +x ~/.config/autostart/nan_gui.desktop</code>
 
==== Add it to the startup scripts ====
{| class="wikitable"
{| class="wikitable"
|+
|+
!Desktop environment
! Desktop Environment !! Menu-Based Instructions !! CLI-Based path
!Adding through menu bar
!Adding directly through command line interface
|-
|-
|KDE 3
| KDE 3 || — || <code>~/.kde/autostart/nan_gui.desktop</code>
|
|~/.kde/autostart/nan_gui.desktop
|-
|-
|KDE4
| KDE 4 || — || <code>~/.kde4/autostart/nan_gui.desktop</code>
|
|~/.kde4/autostart/nan_gui.desktop
|-
|-
|KDE Plasma and newer versions
| KDE Plasma / Newer || System Settings → Startup & Shutdown → Autostart → Add Program… || <code>~/.config/autostart/nan_gui.desktop</code>
|System Settings → Startup & Shutdown → Autostart → Add Program…
|~/.config/autostart/nan_gui.desktop
|-
|-
|GNOME
| GNOME || <code>gnome-tweaks</code> → Startup Applications → '+' || <code>~/.config/autostart/nan_gui.desktop</code>
|Install/launch '''gnome-tweaks''' → ''Startup Applications → ‘+’''
|~/.config/autostart/nan_gui.desktop
|-
|-
|XFCE
| XFCE || Settings Manager → Session & Startup → Application Autostart → Add… || <code>~/.config/autostart/nan_gui.desktop</code>
|Settings Manager → Session & Startup → Application Autostart → Add…
|~/.config/autostart/nan_gui.desktop
|}
|}
==== Step 3: Make it executable: ====
<code>chmod +x ~/.config/autostart/nan_gui.desktop</code>


== NDTS-GUI Main Window ==
== NDTS-GUI Main Window ==
[[File:NDTS-GUI.png|thumb|NDTS GUI]]
[[File:NDTS-GUI.png|thumb|NDTS GUI]]
The NDTS GUI has seven lines and three buttons as described here:


* Top text bar: Shows the status of whether a collected dataset will be harvested or not
{| class="wikitable"
** "Data will be transmitted to NAN"
|+ NDTS-GUI Main Window Elements
** "Data will not be transmitted to NAN"
! Element !! Description
* Middle text bar: Shows whether harvesting is on or off
|-
** "NAN Transport is running"
| Top Text Bar || Indicates whether the dataset will be harvested. Options:
** "Harvesting is suspended"
* "Data will be transmitted to NAN"
* Third text bar: Shows whether TopSpin or VnmrJ is running. Note that if TopSpin / VNMRJ is not running the NAN harvesting setting is irrelevant
* "Data will not be transmitted to NAN"
** "Topspin / VNMRJ is running"
|-
** "Topspin / VNMRJ is not running"
| Middle Text Bar || Shows harvesting status:
* Ignoring job numbers higher than 19999 - States that any jobs collected in a job number higher than the value shown will not be harvested, regardless of the NAN harvesting setting.  
* "NAN Transport is running"
** This value is defined by the facility manager and can be changed in the daemon configuration file. This allows users to run calibration and other experiments that they do not want to be harvested in job numbers higher than the set value where they will not be harvested and avoids the need to toggle harvesting off for such datasets where it is easy to forget to turn it back on.
* "Harvesting is suspended"
* Probe: Lists the probe that the NAN system believes is in the instrument.
|-
** This is simply informational for users to see so that they may let the facility manager know if it is incorrect and will not affect data harvesting if it is wrong. Note that the facility manager sets the currently installed probe from the Facility Dashboard on the NAN web portal and when they do so they apply a date. Therefore, if a probe was physically changed in the instrument, but the facility manager forgot to make the change on the NAN portal, they can do so retroactively and datasets harvested with the incorrect probe will be corrected.
| Third Text Bar || Indicates TopSpin or VnmrJ activity:
* NAN user: Shows the NAN user currently selected.
* "Topspin / VNMRJ is running"
** If no user is selected than it will read "unselected".
* "Topspin / VNMRJ is not running"
*** Note that if the NAN user is unselected than harvesting will default to whatever the facility managers default harvesting setting for unselected users is on the Manage Facility Users tool on the NAN portal.
Harvesting settings are irrelevant if no acquisition software is running.
** Having the correct NAN user selected is important as only the NAN user, their PI, and the facility manager will have access to the datasets within the Dataset Browser. Data associated with the incorrect user can be rectified by the NAN User or PI as long as the true NAN user is within the same lab group or by the facility manager who has the ability to reassign the data to any NAN user. Note that non PI NAN users are restricted to reassigning datasets to others in their lab-groups to within three months from harvesting.
|-
* NAN harvesting: Allows the user to toggle harvesting on/off.
| Ignoring Job Numbers || Datasets collected with job numbers above this threshold are ignored for harvesting. This setting is defined by the facility manager and avoids harvesting test or calibration runs without requiring toggling of the NAN harvesting radio button which is easy to forget to turn back on.
** The ability for a user to toggle this setting is dependent on the whether the facility manager allows it for the given user as is defined on the Manage Facility Users tool. Disallowing harvesting to be turned off can ensure that all data is collected while still allowing users to utilize high job numbers for cases where a calibration or test experiment to not be collected. Likewise, disallowing harvesting to be turned on allows an account where data should never be harvested to not be able to accidently turn it on, such as a commercial entity.
|-
* Enter Experiment Details button: Allows the user to change the selected NAN user and provide additional metadata information and is discussed below
| Probe || Displays the currently assumed installed probe. This value is for informational purposes only and is updated via the NAN portal. If incorrect, it can be retroactively corrected by the facility manager as the facility manager applies a date when a probe swap occurs.
* Manual Harvest button: Allows the user to select a dataset that was inadvertently not harvested to be selected and sent to the NAN archive.
|-
| NAN User || Indicates the currently selected NAN user. If unselected, harvesting defaults to facility manager-defined fallback behavior. Accurate user selection is essential for proper dataset access and reassignment.
|-
| NAN Harvesting Toggle || Allows users to enable/disable harvesting. Permissions for toggling are set by the facility manager. Restrictions ensure harvesting behavior is consistent with user roles (e.g., preventing harvesting by commercial users).
|-
| Enter Experiment Details || Opens a window to enter metadata and change the selected NAN user (see next section).
|-
| Manual Harvest || Allows manual selection of a previously unharvested dataset for submission to the NAN archive (see below)
|}


== NDTS Experimental Details Window ==
== NDTS Experimental Details Window ==
[[File:Experiment-details.png|thumb|450x450px|Experiment Details Window]]
[[File:Experiment-details.png|thumb|450x450px|Experiment Details Window]]
The Experimental Details window allows the NAN user to be changed and metadata to be entered which will then be associated with collected datasets


* NAN user: Allows the operator to select from a list of NAN users.
{| class="wikitable"
** The list of users are those defined by the facility manager from the Manage Facility Users tool and the ability of a workstation user to change the NAN user is also controlled from the Manage Facility Users tool
|+ Experimental Details Fields
* Project / Study / Sample: The Projects, Studies, and Samples for the selected NAN user are provided as pull-down lists.
! Field !! Description
** This allows users to associate datasets with Projects and Studies and assign Samples at the time of data collection. These assignments can be done later in the dataset browser as well.
|-
* Refresh button: The NAN user lists along with users projects, studies, and samples are pulled automatically every 10 minutes so that changes on the NAN portal are reflected in the NAN GUI in a reasonable time frame. However, in the event that a user is entering data at the same time of setting up data collection (e.g. creating a sample), than they may force a refresh of the user, project, study, and sample lists immediately.
| NAN User || Allows selection from the facility-defined list of NAN users. Permission to change users is governed by the facility manager.
* Solution / Solid toggle: Selects whether the dataset is a solution or solids dataset. In addition to adding that metadata to the datasets it also changes the additional metadata fields available on the screen
|-
* Magic angle spinning: Toggle to indicate that the dataset is collected with magic angle spinning
| Project / Study / Sample || Drop-down lists enable assignment of datasets to a specific project, study, and sample at the time of data collection. These assignments can also be updated later in the Dataset Browser.
* MAS rate (kHz): Allows the MAS spinning rate to be entered for cases where the rate is not properly stored in the experimental parameter sets
|-
* Z0drift correction: Allows the Z0 drift rate, if known, to be entered allowing that metadata to be captured with the datasets
| Refresh Button || Forces immediate update of user, project, study, and sample lists, which are otherwise refreshed every 10 minutes.
* Multi-receiver and time sharing checkboxes: can be checked if either apply
|-
* Notes: User defined text that can be associated with datasets
| Solution / Solid Toggle || Indicates whether the dataset is from a solution or solid-state sample. This also determines which additional metadata fields are shown.
 
|-
 
| Magic Angle Spinning || Toggle to indicate that MAS was used during acquisition.
== Overview ==
|-
An NDTS installation on a spectrometer workstation has two parts:
| MAS Rate (kHz) || Field to enter the MAS spinning rate if not present in the dataset parameters.
 
|-
* **NDTS daemon** – runs as a background service, harvesting datasets. 
| Z0 Drift Correction || Allows entry of the known Z0 drift rate for inclusion in metadata.
* **NDTS-GUI** – shows harvesting status and lets users set the NAN user, toggle harvesting, and add metadata.
|-
 
| Multi-receiver / Time Sharing Checkboxes || Optional indicators that can be checked if either condition applies to the dataset.
When harvesting is **On**, datasets are captured automatically as each experiment finishes; with harvesting **Off**, users can still harvest manually from the GUI.
|-
 
| Notes || Free-text field for entering user-defined notes to be associated with the dataset.
== Mapping NAN users to workstation accounts ==
|}
Every harvested dataset must belong to a NAN user to appear in the Dataset Browser. 
Mappings between workstation logins and NAN users are set by the facility manager in **Facility&nbsp;Dashboard → Manage Facility Users**.
Users may change the selected NAN user in the GUI only if the manager allows it.


== NDTS harvesting defaults ==
== Manual Harvest Window ==
Default behaviour—harvesting state, job-number cutoff, treatment of unmapped users—is defined in **Manage Facility Users**. 
The manual harvest button allows users to harvest a dataset in cases where automatic data harvesting was unintentionally disabled. It is not intended for harvesting older datasets; the NAN portal provides an [[Arbitrary Dataset Upload|'''arbitrary data upload''']] feature for that purpose.
These settings refresh whenever the GUI starts or the selected NAN user changes. If the GUI is not running, the daemon uses those defaults unchanged.


== Launching the NDTS-GUI ==
=== Limitations ===
Because harvesting status and metadata should always be visible, configure the GUI to autostart on login. (The window’s close button is disabled to prevent accidental exit.)


=== Manual start ===
* On VNMRj, the manual upload must be from an experiment directory (e.g. <code>/$home/vnmrsys/exp''N''</code>)
<syntaxhighlight lang="bash">
* VNMRj or TopSpin must be running
/opt/nan-dtdaemon/nan_gui
* The NDTS-GUI must be running
</syntaxhighlight>
** Harvesting must be set to "on"
** Correct NAN user, project, study, sample, and additional metadata must be selected or entered
* Current spectrometer, probe, and related metadata will be associated with the dataset. Therefore, this feature should only be used for recently collected datasets


=== Automatic start ===
[[File:Manual-harvest.png|thumb|450x450px|Manual Harvest Window]]
Identify the desktop environment:
<syntaxhighlight lang="bash">
echo $XDG_CURRENT_DESKTOP    # or  echo $DESKTOP_SESSION
</syntaxhighlight>


Create the launcher file and make it executable:
=== Description of Manual Harvest Pop-up Window ===
<syntaxhighlight lang="ini">
[Desktop Entry]
Type=Application
Exec=/opt/nan-dtdaemon/nan_gui
Hidden=false
NoDisplay=false
Name=NAN GUI
Comment=NDTS graphical interface
X-GNOME-Autostart-enabled=true
</syntaxhighlight>
<syntaxhighlight lang="bash">
chmod +x ~/.config/autostart/nan_gui.desktop
</syntaxhighlight>


{| class="wikitable"
{| class="wikitable"
! Desktop environment !! Menu method !! File method
! Field !! Description
|-
| '''User''' || Displays the current workstation username (informational only)
|-
| '''Experiment Location''' || Dialog box to select the dataset to be harvested; includes a Browse button for easier navigation
|-
|-
| KDE 3 || – || <code>~/.kde/autostart/nan_gui.desktop</code>
| '''Force''' || Forces harvesting of a dataset even if it has already been harvested; overrides the default behavior
|-
|-
| KDE 4 || – || <code>~/.kde4/autostart/nan_gui.desktop</code>
| '''History''' || Opens the history of previously manually harvested datasets (see below)
|-
|-
| KDE Plasma (5 +) || *System Settings → Startup & Shutdown → Autostart → Add Program…* || <code>~/.config/autostart/nan_gui.desktop</code>
| '''Harvest''' || Starts the harvesting process; disabled until a dataset is selected
|-
|-
| GNOME || *gnome-tweaks → Startup Applications → ‘+’* || <code>~/.config/autostart/nan_gui.desktop</code>
| '''Done''' || Closes the Manual Harvest window
|-
|-
| XFCE || *Settings Manager → Session & Startup → Application Autostart → Add…* || <code>~/.config/autostart/nan_gui.desktop</code>
| '''Status Line''' || Displays the result of the last harvesting attempt
|}
|}


== NDTS-GUI Main Window ==
==== History Window ====
[[File:NDTS-GUI.png|thumb|NDTS GUI]]


{| class="wikitable"
{| class="wikitable"
! Element !! Purpose !! Typical states / notes
! Field !! Description
|-
| **Status 1** || Indicates if the next dataset will be harvested. || *Data will be transmitted to NAN* / *Data will not be transmitted to NAN*
|-
| **Status 2** || Current harvesting state. || *NAN Transport is running* / *Harvesting is suspended*
|-
| **Status 3** || Whether TopSpin / VNMRJ is running. || *TopSpin / VNMRJ is running* / *not running*
|-
| **Job-number cutoff** || Jobs above this number are ignored. || Value set by facility manager
|-
|-
| **Probe** || Probe the system believes is installed. || Informational; manager can correct retroactively
| '''Date''' || Date the dataset was manually harvested (not the date of dataset acquisition)
|-
|-
| **NAN user** || Current user or <code>unselected</code>. || Determines dataset visibility
| '''NAN User''' || The NAN user selected at the time of manual harvesting; this is the user the dataset will be associated with
|-
|-
| **Harvesting toggle** || Turn harvesting On/Off. || User access controlled in *Manage Facility Users*
| '''Path''' || Filesystem path of the manually harvested dataset
|-
|-
| **Enter Experiment Details…** || Opens the Experiment Details window. ||
| '''Status''' || Status of the manual harvest (e.g., success, error)
|-
|-
| **Manual Harvest…** || Harvest a missed dataset. ||
| '''Refresh''' || Button to refresh the history list; otherwise, it updates only when the window is reopened
|}
|}


== Experiment Details Window ==
[[File:Experiment-details.png|thumb|450x450px|Experiment Details Window]]


== Manual Harvesting from the Command Line Interface (CLI) ==
=== Linux ===
For Linux workstations, run the executable <code>/opt/nan-dtdaemon/nan_sendexp</code> and supply the command-line arguments described below.
TopSpin and the '''NDTS Workstation Daemon''' must be running.
=== Windows ===
On Windows, invoke the batch file <code>C:\opt\nan-dtdaemon\nan_sendexp.bat</code> from a '''CMD''' session.
The '''NDTS Workstation Daemon''' must be running.
=== Command-Line Arguments ===
{| class="wikitable"
{| class="wikitable"
! Field / control !! Function / options
! Argument !! Description !! Examples
|-
| **NAN user** || Choose from users allowed on this workstation.  Access defined in *Manage Facility Users*.
|-
| **Project / Study / Sample** || Pulldown lists let users link datasets to projects, studies, and samples at acquisition time.
|-
| **Solution / Solid toggle** || Sets sample state and reveals relevant fields.
|-
|-
| **Magic Angle Spinning** || Checkbox.
| <code>'''--status'''</code> || Returns the current workstation user's history of manual-harvest attempts. Supports <code>--username</code> to view another user's history. || <code>/opt/nan-dtdaemon/nan_sendexp --status</code><br/><code>/opt/nan-dtdaemon/nan_sendexp --status --username={username}</code>
|-
|-
| **MAS rate (kHz)** || Enter spinning rate if not stored in parameters.
| <code>'''--harvest'''</code> (default) || Harvests a dataset.<br/><br/>'''Options'''<br/><code>--username={username}</code> – harvest as another user.<br/><code>--force</code> – re-harvest even if previously harvested.<br/><code>--topspin={topspin_location}</code> – TopSpin root path (required on Windows). || <code>/opt/nan-dtdaemon/nan_sendexp {experiment_location}</code><br/><code>/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location}</code><br/><code>/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location} --username={username}</code><br/><code>/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location} --force</code><br/><code>/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location} --topspin=C:\Bruker\topspin4.3.0</code>
|-
|-
| **Z0 drift correction** || Enter drift rate (if known).
| <code>'''--ignore'''</code> || Instructs the NDTS daemon to ignore harvesting settings from the NDTS-GUI (useful for scripted calibration experiments when only certain calibrations experiments need to be harvested). || <code>/opt/nan-dtdaemon/nan_sendexp --ignore</code>
|-
|-
| **Multi-receiver** || Checkbox.
| <code>'''--detect'''</code> || Re-enables adherence to NDTS-GUI harvesting settings (reversed the effect of <code>--ignore</code>). || <code>/opt/nan-dtdaemon/nan_sendexp --detect</code>
|-
|-
| **Time-sharing** || Checkbox.
| <code>'''--retcode'''</code> || Prepends a status character to output ('''1''' = success, '''0''' = failure) for programmatic use. || <pre>0Unable to determine experiment type for…</pre>
|-
|-
| **Notes** || Free-text notes stored with each dataset.
| <code>'''--verbose'''</code> || Prints detailed diagnostic output. || —
|-
|-
| **Refresh** || Update user, project, study, and sample lists immediately (auto-refresh occurs every 10 min).
| <code>'''--help'''</code> || Displays built-in command-line help. || —
|}
|}

Latest revision as of 12:29, 20 June 2025

Overview

NDTS installations on the spectrometer workstation consist of the daemon, which runs as a service, and the NDTS graphical user interface (NDTS-GUI), which displays status information and allows users to adjust harvesting status, select the NAN user, and provide metadata to be associated with datasets. NDTS is designed to automatically harvest datasets upon completion when harvesting is enabled. Manual harvesting can also be performed via the NDTS-GUI.

Important Note: For TopSpin 4.x and VNMRj the daemon will automatically detect when experiments are complete, but for TopSpin < 4.x each user must enable Accounting from their TopSpin account for the daemon to recognize when experiments complete

Instructions for turning on Accounting for TopSpin < 4.0

Mapping NAN users to spectrometer workstation users

Each harvested dataset must be associated with a NAN user to be visible in the Dataset Browser. This association is managed primarily through the NDTS-GUI, where the selected NAN user can be changed (if permitted by facility manager settings). By default, the NAN user mapped to the current spectrometer workstation user is selected. These mappings are managed by the NMR facility manager through the user management page on the NAN portal Facility Dashboard.

NDTS harvesting defaults

Facility managers use the Manage Facility Users tool on the Facility Dashboard to:

  • Add NAN users to the facility
  • Map users to spectrometer workstation accounts
  • Set default harvesting preferences
  • Define fallback behavior for unmapped users

When the NDTS-GUI is launched or when the selected NAN user is changed, the default harvesting settings are refreshed based on the configuration in the *Manage Facility Users* tool.

If the NDTS-GUI is not running, NDTS harvesting defaults to the fallback settings defined in the Manage Facility Users tool.

Launching the NDTS-GUI

It is essential that the NDTS-GUI remain running so that harvesting status is visible and users can ensure appropriate metadata and settings are applied before data collection. To prevent accidental closure, the close button in the GUI is disabled once launched. It is strongly recommended to configure the NDTS-GUI to start automatically upon login to the spectrometer workstation.

Manually launching the NDTS-GUI

While automatic launching is preferred, the GUI can be started manually with:

/opt/nan-dtdaemon/nan_gui

Automatically launching the NDTS-GUI

The setup depends on the desktop environment and whether the configuration is per-user or system-wide. Below are instructions for different desktop environments, but with so many different versions and different Linux distros it is impossible to cover all possibilities. That said, launching an applications upon login is a common task as the correct answer can usually be found easily with a Google search or by asking one of the LLMs such as ChatGPT.

Step 1: Identifying the desktop environment

Use this command to determine your current desktop environment

echo $XDG_CURRENT_DESKTOP

if the above command does not work or show output try:

echo $DESKTOP_SESSION

Step 2: Creating the launcher script (if adding from the CLI)

If you are adding the launcher script through the command line interface you will need to create the text file below using your favorite editor and save it to the appropriate location (see the table below of the CLI-based path)

[Desktop Entry]
Type=Application
Exec=/opt/nan-dtdaemon/nan_gui
Hidden=false
NoDisplay=false
Name=NAN GUI
Comment=NDTS graphical interface
X-GNOME-Autostart-enabled=true

Most Linux distros also have the ability to add a launcher through the menu bar. Below in the table follow the directions for the Menu-Based instructions to add the launcher and select /opt/nan-dtdaemon/nan_gui as the program to launch

Desktop Environment Menu-Based Instructions CLI-Based path
KDE 3 — ~/.kde/autostart/nan_gui.desktop
KDE 4 — ~/.kde4/autostart/nan_gui.desktop
KDE Plasma / Newer System Settings → Startup & Shutdown → Autostart → Add Program… ~/.config/autostart/nan_gui.desktop
GNOME gnome-tweaks → Startup Applications → '+' ~/.config/autostart/nan_gui.desktop
XFCE Settings Manager → Session & Startup → Application Autostart → Add… ~/.config/autostart/nan_gui.desktop

Step 3: Make it executable:

chmod +x ~/.config/autostart/nan_gui.desktop

NDTS-GUI Main Window

NDTS GUI
NDTS-GUI Main Window Elements
Element Description
Top Text Bar Indicates whether the dataset will be harvested. Options:
  • "Data will be transmitted to NAN"
  • "Data will not be transmitted to NAN"
Middle Text Bar Shows harvesting status:
  • "NAN Transport is running"
  • "Harvesting is suspended"
Third Text Bar Indicates TopSpin or VnmrJ activity:
  • "Topspin / VNMRJ is running"
  • "Topspin / VNMRJ is not running"

Harvesting settings are irrelevant if no acquisition software is running.

Ignoring Job Numbers Datasets collected with job numbers above this threshold are ignored for harvesting. This setting is defined by the facility manager and avoids harvesting test or calibration runs without requiring toggling of the NAN harvesting radio button which is easy to forget to turn back on.
Probe Displays the currently assumed installed probe. This value is for informational purposes only and is updated via the NAN portal. If incorrect, it can be retroactively corrected by the facility manager as the facility manager applies a date when a probe swap occurs.
NAN User Indicates the currently selected NAN user. If unselected, harvesting defaults to facility manager-defined fallback behavior. Accurate user selection is essential for proper dataset access and reassignment.
NAN Harvesting Toggle Allows users to enable/disable harvesting. Permissions for toggling are set by the facility manager. Restrictions ensure harvesting behavior is consistent with user roles (e.g., preventing harvesting by commercial users).
Enter Experiment Details Opens a window to enter metadata and change the selected NAN user (see next section).
Manual Harvest Allows manual selection of a previously unharvested dataset for submission to the NAN archive (see below)

NDTS Experimental Details Window

Experiment Details Window
Experimental Details Fields
Field Description
NAN User Allows selection from the facility-defined list of NAN users. Permission to change users is governed by the facility manager.
Project / Study / Sample Drop-down lists enable assignment of datasets to a specific project, study, and sample at the time of data collection. These assignments can also be updated later in the Dataset Browser.
Refresh Button Forces immediate update of user, project, study, and sample lists, which are otherwise refreshed every 10 minutes.
Solution / Solid Toggle Indicates whether the dataset is from a solution or solid-state sample. This also determines which additional metadata fields are shown.
Magic Angle Spinning Toggle to indicate that MAS was used during acquisition.
MAS Rate (kHz) Field to enter the MAS spinning rate if not present in the dataset parameters.
Z0 Drift Correction Allows entry of the known Z0 drift rate for inclusion in metadata.
Multi-receiver / Time Sharing Checkboxes Optional indicators that can be checked if either condition applies to the dataset.
Notes Free-text field for entering user-defined notes to be associated with the dataset.

Manual Harvest Window

The manual harvest button allows users to harvest a dataset in cases where automatic data harvesting was unintentionally disabled. It is not intended for harvesting older datasets; the NAN portal provides an arbitrary data upload feature for that purpose.

Limitations

  • On VNMRj, the manual upload must be from an experiment directory (e.g. /$home/vnmrsys/expN)
  • VNMRj or TopSpin must be running
  • The NDTS-GUI must be running
    • Harvesting must be set to "on"
    • Correct NAN user, project, study, sample, and additional metadata must be selected or entered
  • Current spectrometer, probe, and related metadata will be associated with the dataset. Therefore, this feature should only be used for recently collected datasets
Manual Harvest Window

Description of Manual Harvest Pop-up Window

Field Description
User Displays the current workstation username (informational only)
Experiment Location Dialog box to select the dataset to be harvested; includes a Browse button for easier navigation
Force Forces harvesting of a dataset even if it has already been harvested; overrides the default behavior
History Opens the history of previously manually harvested datasets (see below)
Harvest Starts the harvesting process; disabled until a dataset is selected
Done Closes the Manual Harvest window
Status Line Displays the result of the last harvesting attempt

History Window

Field Description
Date Date the dataset was manually harvested (not the date of dataset acquisition)
NAN User The NAN user selected at the time of manual harvesting; this is the user the dataset will be associated with
Path Filesystem path of the manually harvested dataset
Status Status of the manual harvest (e.g., success, error)
Refresh Button to refresh the history list; otherwise, it updates only when the window is reopened


Manual Harvesting from the Command Line Interface (CLI)

Linux

For Linux workstations, run the executable /opt/nan-dtdaemon/nan_sendexp and supply the command-line arguments described below.

TopSpin and the NDTS Workstation Daemon must be running.

Windows

On Windows, invoke the batch file C:\opt\nan-dtdaemon\nan_sendexp.bat from a CMD session.

The NDTS Workstation Daemon must be running.

Command-Line Arguments

Argument Description Examples
--status Returns the current workstation user's history of manual-harvest attempts. Supports --username to view another user's history. /opt/nan-dtdaemon/nan_sendexp --status
/opt/nan-dtdaemon/nan_sendexp --status --username={username}
--harvest (default) Harvests a dataset.

Options
--username={username} – harvest as another user.
--force – re-harvest even if previously harvested.
--topspin={topspin_location} – TopSpin root path (required on Windows).		 /opt/nan-dtdaemon/nan_sendexp {experiment_location}
/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location}
/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location} --username={username}
/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location} --force
/opt/nan-dtdaemon/nan_sendexp --harvest {experiment_location} --topspin=C:\Bruker\topspin4.3.0
--ignore Instructs the NDTS daemon to ignore harvesting settings from the NDTS-GUI (useful for scripted calibration experiments when only certain calibrations experiments need to be harvested). /opt/nan-dtdaemon/nan_sendexp --ignore
--detect Re-enables adherence to NDTS-GUI harvesting settings (reversed the effect of --ignore). /opt/nan-dtdaemon/nan_sendexp --detect
--retcode Prepends a status character to output (1 = success, 0 = failure) for programmatic use. 
0Unable to determine experiment type for…
--verbose Prints detailed diagnostic output. —
--help Displays built-in command-line help. —
Retrieved from "https://wiki.usnan.org/index.php?title=NDTS-GUI&oldid=1016"