From MdsWiki

Revision as of 15:32, 2 October 2015

jScope is a MDSplus tool providing a sophisticated graphical interface to acquired waveforms.
We know now that a MDSplus tree can contain several kinds of data, among which arrays and signals. If we use jTraverser to look at the content of a node containing an acquired signal, we would see something like the following:

a very looooong expression (note the scroll bar). In fact acquired signals are usually made of thousands of points, and looking at the textual format of the corresponding expression is useless. Much better an interface like the following:

showing the same (evaluated) expression of the previous example.

This interface is provided by the jScope tool, a Java application for graphical waveform display. In general, jScope allows the definition of a number of panels, and associated with each panel with one or more MDSPlus expressions (usually signal references), returning an array of numbers, which are then plotted in the panel.

How to set-up a jScope Panel

In order to start learning how using jScope, let's start from the running example of the first tutorial application presented in the first section of this tutorial.
Consider the jScope application of the tutorial entitled Scope - jScope/Tutorial_3.jscp . Click the right mouse button over the top panel and select Setup data source ... menu option:



The following dialog will appear. It defines all the required information to associate one or more waveforms to the target panel:


Some parameters listed in the dialog are global parameters for the targe panel, others are associated with single waveforms. If more than one waveform is specified, as in this example, click on the corresponding waveform in the Signal list for the association.
The global parameters are the following:

• Title: the title of the panel. This field, as other ones, specifies a MDSplus expression. This is useful, for example, in case the title of the panel refers to some explanatory test stored in the pulse file. In the case a string is directly specified in that field, it must be put in quotes.
• Y Label: The label associated with the Y axis (MDSplus expression)
• Y min, Y max: specify the Y value range (MDSplus expression). When any field is empty, the minimum (maximum) Y value of the signal is taken.
• X Label: The label associated with the X axis (MDSplus expression)
• Y min, Y max: specify the Y value range (MDSplus expression). When any field is empty, the minimum (maximum) X value of the signal is taken.
• Experiment: the name of the experiment from which waveforms are taken.
• Shot: the shot number.
• Update Event: the name of the MDSplus event triggering the waveform display. Events are described in the tutorial section on MDSplus events.
• Default node: the default position in the pulse file, meaninful only if relative paths are used. This field is used vary seldomly.

The parameters associated with the specific waveform are the following:

• Signal Label: The label string associated with the selected signal and displayed in the signal legend. Signal legends are displayed and hidden by popup option Position Legend and Remove Legend, respectively.
• Y: the Y value of the waveform. It is expressed as a MDSplus expression which is expected to return an array.
• X: the MDSplus expression returning the X axis of the signal. This field is optional. If empty, jScope derives the X axis from the Y definition of the signal. If the expression returns a Signal data type, the X values are derived from the dimension of the signal itself (recall that the signal data type specifies samples (Y) and times(X)). If the expression returns an array, the indexes of the samples are displayed in the X axis.

A toggle button is displayed on the left of every global parameter: when checked, the value of the corresponding parameter is not directly editable in the form, but it is taken from the Global Setting parameters. Global setting is configurable via Customize->Global Setting... menu bar option. The displayed dialog, shown below, allows setting the waveform independent fields which are valid for every jScope panel.



The graphical appearance of the displayed waveforms can be defined by means of the four option menus displayed on the right in the bottom Signal lists section. From top to bottom they are:

• Line option: when Line, line connecting sampling points is shown. When No Line the line is not displayed. When Step Plot, the drawn line connecting every two sampling points is horizontal.
• Dimension option: this option is used only in advanced jScope configurations involving 2D signals. For normal waveforms it is always set to y & time. We shall see that other categories of 2 D signals, such camera frames, are handled by jScope using a different setup interface.
• Color option: specifies the color of the associated waveform.
• Marker option: specifies the drawn marked for sampling points.

Other options available in the top right part of the Wave Setup dialog:

• Expand Expr. : the push button displays a larger window for typing expressions for X and Y fields. Useful for long expressions
• Log scale: logaritmic scale for X or Y axis. Very seldomly used.
• Is image: switches to frame visualization set-up. See the following sections.
• Error: defines error bars for the selected signal. When the button is pressed, a popup window is shown there the error bar for that signal can be specified. The name typed will refer to a signal with the same number of points of the associated signal yielding the error value for every point.

A useful parameter when using jScope to look at the waveform acquired in different pulse files is the Shot field in the bottom of jScope. The normal use case is to avoid defining the shot number in the Setup Data source dialog (that is, selecting the associated check button) so that jScope takes the shot number from the bottom Shot field. In this case, the shot number in that field a global number for all the displayed panels after the Apply button on its right has been pushed.

Manipulating Waveforms

Once waveforms have been displayed in the jScope panels, they can be manipulated in order to easily retrieve useful information. jScope supports the following modes of operation, selectable via the radio buttons on the bottom left part of the window:

• Point: in this mode of operation, a crosshair is displayed in every panel and it can be dragged. Whendragging the crosshair in one panel, the crosshais shown in the other panes mode accordingly to the current position in the X axis. X and Y values are prined in the bottom status line. When multiple windows are displayed on the same panel, the crosshair is attached to the waveform which is closest to the mouse when the left mouse button is pressed.
• Zoom: in this mode of operation it is possible to zoom portions of waveforms. A combined usage of zoom and crosshair is very useful for discovering relationships among signals. A typical use case is to enlarge a portion of waveform in zoom mode in one panel to highlight an interesting phenomenon. Then, in Point mode, when the central mouse button is clicked over the enlarged signal, all the signals in the other panels are scaled at the same way, thus highlighting possible relationships among signals.
• Pan: in this mode of operation waveforms can be dragged. Useful after zooming.
• Copy: used to copy the configuration of entire panels into others. In this mode of operation, use the left mouse button to copy panel configuration and the central mouse button to paste the copied configuration into the target panel.

Other options are available in the popup menu activated by pressing the right mouse button on the target panel. Some of them are specific to the panel over which the right mouse button has been pressed, others are global, and others refer to a single waveform in the target panel. In the latter case the option is enabled only in Point mode, so that a single waveform is selected by the crosshair. Most of the options are self-explaining and are enabled only if meaningful in the current context.

jScope Configuration

The number of panels displayed by jScope can be configured via Customize->Window... menu option. When selected, the following dialog is shown

where the number of panels for each columns can be specified, up to a maximum number of 16 panels for every column (max 4). Therefore up to 64 panels can be displayed by a single jScope application.

Setting up a jScope configuration, possibly involving a large number of panels, is a lengthy process, however the current jScope configuration can be saved in a configuration file so that it can be retrieved later. This approach represents the typical usage of jScope: users prepare a set of configurations for jScope and then forget about manual jScope set-up, they simply recall their saved configurations.
To save the current jScope configuration, use ither menu option
Customize->Save current setting
or
Customize->Save current setting as...
The latter allows you specify the name or location of the configuration file (by default jScope configuration files have .jscp extension). The former is enabled when the current jScope setting has been read from a configuration file, and is used to update it after making some changes in configuration.
Configurations are loaded via either menu command
Customize->Use last saved setting
or
Customize->Use saved setting from...
The latter command allows you to choose the configuration file. By default jScope writes configuration files in the jScope directory, created in the user home directory.

Connecting jScope to data sources

jScope is a generic tool for data visualization and can be connected to a variety of data sources, not necessarily related to MDSplus. It is also possible to develop plugins for jScope so that other data formats and sources can be visualized in jScope. In order to develop a new jScope plugin for a new data source, it suffices to develop a Java class implementing the jScope.DataProvider interface.
In the large majority of application, however, jScope is used to display MDSplus data, using either data provider:

• MdsDataProvider
• LocalDataProvider

Even the two data providers give access to MDSplus data, they have an important difference which should be understood in order to use the best jScope configuration.
MdsDataProvider provides access to MDSplus data via mdsip, that is, the remote data access interface. In order to use MdsDataProvider as data source, it is necessary to have a mdsip server running in the node hosting the MDSplus pulse files. The configuration of the data provider will specify the IP address and the port number of the target mdsip server.
LocalDataProvider provides direct access to MDSplus data via Java Native Interface (JNI). This means that the jScope application links directly to the MDSplus libraries for data access, without connecting to a mdsip server, that is, without using the network to retrieve waveforms.
When using MdsDataProvider, the jScope application is a pure Java application and there is no need to have any MDSplus library installed on the machine, it suffices having env variable CLASSPATH containing jScope.jar. Moreover, using MdsDataProvider, jScope performs on the fly data resampling in order to handle very large waveforms (up to several hundreds of MBytes of data) without running out of memory in the Java Virtual Machine.
Since such an optimization is not possible when linking against MDSplus libraries in JNI, as done by LocalDataProvider, MdsDataProvider should be used whenever possible (that is, whenever a mdsip data server is available).

The available data servers are shown in Network->Servers menu. A default list is provided in jScope distribution, but it is unlikely that any will work on your specific installation, except Local (referring to LocalDataProvider). It is therefore necessary to configure one or more data providers for the specific data environment. The list of data servers can be modified and configured using the menu command Network->Edit server list.... The displayed form is shown below:

The above figure refers to the common configuration of a MdsDataProvider instance. The class is selected in the Server Class field. Server Argument defines a specific argument for the data provider which for MdsDataProvider is of the form <IP address>:<Port> (when Port is omitted, the default port number 8000 is assumed). Field Server Label specifies the name which is displayed in the Network->Servers list. Observe that multiple Data Providers can be defined in jScope allowing switching from one data source to another.
The current data provider definition is saved in jScope configurations, but is lost when other jScope configurations are used. For this reason, a better way to specify the supported data providers in jScope is by configuring the jScope property file as explained in the next paragraph.

The jScope property file

We shall describe here very briefly the features of jScope concentrating more on the way jScope connects to a data source. Basically, jScope connects a panel to a set of signals by means of the Setup Data Dialog, activated by selecting the pop-up option Setup data source... getting the following dialog:

The setup data dialog has several fields, mostly optionals. The field Y is mandatory and defines the expression to be evaluated. In the above example, as in most cases, the expression is a reference (a tag name here) to a node of a MDSplus tree. If the X field is not specified, jScope defines as the X axis either the sequence of integer numbers, in the case the evaluation of the Y expression returns an array, or the time values of the specified signal in the case the evaluation of the Y expression returns a signal (i.e. the MDSplus data type specifying both an Y and a X axis).

In the above example, two other fields have been filled: the experiment, i.e. the name of the MDSPlus tree containing the data to be displayed, and the shot number.
You will note also that a checkbox is associated with every field. When selected, the checkbox indicates that the value of the corresponding field is retrieved from the global settings. The global settings form is activated via the Customize->Global Settings... option. In particular, it is convenient to let the default setting of the shot number, and then to type the actual shot number (which is often changed) in the bottom Shot: label of jScope.

So far we have seen how to connect a jScope panel to one (or more) signals stored in a MDSplus tree. This is however not enough for a complete specification of the signal. In fact we need to define also where is the MDSplus tree. The location of the MDSplus tree is specified by defining an appropriate Data Server using the Network->Servers pulldown menu.
We shall see in the following sections how MDSplus data are exported. We anticipate here that MDSplus data hosted on a system can be exported by running an application called mdsip. This application exports the content of the local trees over TCP/IP top any connected client running jScope. When data is accessed locally, and no mdsip server is active, jScope reads local data using the local MDSplus data access routines. In this case it is necessary to define the Local Data Server. As in this case jScope links directly to the MDSplus libraries, you need to have MDSplus installed on your machine, and an appropriate definition of the environment variable PATH (for windows) or LD_LIBRARY_PATH (for Unix), defining the directory containing the MDSplus libraries (usually \Program Files\mdsplus if you installed MDSplus on windows, or /usr/local/mdsplus/lib on Unix).

When data is accessed on a remote node, there is no need of installing the MDSPlus libraries on the machine running jScope (which is this case is a pure Java application), as jScope handles directly in Java the communication protocol.
To connect jScope on a MDSplus tree on another machine the following steps are required:

1. Start a mdsip server on the machine hosting the MDSplus tree. Let's assume that you are using the default port 8000.
2. Edit a new Data Server to be added in the Server list of jScope, through option Network->Edit server list...
3. The following for is activated:
   

Fill fields Server label: with a name of your choice, Server argument: with the IP address and port of the machine running the mdsip server, separated by a colon, and select MdsDataProvider as Server class. Once you have pressed the Add button, your data server is added to the server list of jScope, and once you have selected the newly created server in the servers list, jScope is connected to your data source via the mdsip server (the currently selected data server is displayed in the bottom right label of jScope).

You may wonder whether it is necessary to repeat all those steps each time jScope is started again. The answer is no, of course, and there are two ways for storing this information:

1. Once you have defined your data server, and connected each panel to one (or more signals), you may save the current configuration in a configuration file using the Customize->Save Current setting as... option. When a jScope is started, you can retrieve the saved configuration by means of the Customize->Use saved settings from... option.
2. You can permanently add your data server to the server list of jScope (as well as change this list) by editing the properties file used by jScope. You can edit this file directly within jScope by selecting the File->properties... option. You add the above definition of your data serer by writing the following lines (where n is the index position of your server in the server list):
   

jScope.data_server_<n>.name = My server
jScope.data_server_<n>.argument = 130.237.47.75:8000
jScope.data_server_<n>.class = MdsDataProvider

To learn more on jScope

You can find a complete description by selecting the Help->About jScope menu option, or through this link)