spec Data File Extension for Visual Studio Code

The extension enhances user experiences in browsing spec data files with Visual Studio Code. spec data files referred to here are files the spec software outputs during various scan commands; the official spec PDF manual call them standard data file format.

spec does not specify the filename extension for this data format. While this VS Code extension treats .spec as the default file extension for the files (language identifier: spec-data), a user can change the association by oneself. Read Language Support in Visual Studio Code (official document of VS Code) for further details.

The extension additionally supports the following formats:

chiplot file format (language identifier: chiplot, default extension: .chi): a text file format in which fit2d software imports and exports one-dimensional dataset such as scattering profiles.
MCA file format (language identifier: spec-mca, default extension: .mca): a text file format in which each row consists of an array of number and represents a spectrum or profile of some data. The separator may be a tab or whitespace. MCA (multichannel analyzer) data in spec can be easily exported in this format by array_dump() function. A MCA files created by ESRF's spec macro, BLISS / mca.mac, are also supported.

What's spec?

spec is internationally recognized as the leading software for instrument control and data acquisition in X-ray diffraction experiments. It is used at more than 200 synchrotrons, industrial laboratories, universities and research facilities around the globe.

cited from CSS - Certified Scientific Software homepage.

Note that the extension is not the official one developed by Certified Scientific Software. Use GitHub issues for bug reports and feature requests about the extension.

Features

Syntax highlighting
Code navigation (only for spec-data)
- Listing symbols in the active editor: the list shown in the outline view in the Explorer viewlet and breadcrumbs at the top of the editor view
Code folding (only for spec-data)
Preview
- motor positions just before a scan in a table view (only for spec-data)
- scan data depicted in a graphical and interactive graph, powered by Plotly.js. A user can select a pair of columns to be drawn.
- scroll sync of the editor and preview (Currently only scroll-preview-from-editor functions; scroll-editor-from-preview does not.)

screenshot

Requirements

Nothing.

Extension Settings

This extension contributes configuration options, accecible from the Settings editor (Win/Linux: Ctrl+,, Mac: Cmd+,). Read Visual Studio Code User and Workspace Settings for details about the Settings window.

Plotly.js template

The extension internally switches Plotly.js templates in order to coordinate the appearance of graphs with the four kinds of VS Code color themes. A user can modify the appearance by overriding the templates via the spec-data.preview.plot.templates configuraiton option.

The option shall be passed as a JSON object consisting of at most 4 key-value pairs. The key shall be either "light", "dark", "highContrast", or "highContrastLight" and the value shall be a Plotly.js template object for the color theme the corresponding key represents. The following example code in the setting.json file makes the line color green in the light theme.

{
    "spec-data.preview.plot.templates": {
        "light": {
            "data": [
                {"type": "scatter", "line": { "color": "#00FF00" } }
            ]
        }
    }
}

The default template objects for the respective color themes can be found in /src/plotTemplate.ts in the GitHub repository. This may help a user to find the name of an attribute he/she wants to change. See the Plotly.js Reference for the complete list of the Plotly.js template attributes.

Known Issues

Limitation due to rendering resource

VS Code provides Webview API for extension authors to implement graphically rich contents. As its name suggests, the content may be prepared as a webpage, i.e., an aggregate of HTML/CSS/JavaScript. This extension employs Plotly.js to plot graphs in the HTML body. While Plotly.js looks performant as an interactive and nice-looking graph generator, to render a preview consisting of a large number of scan dataset cosumues both CPU and memory resources. For this reason, the maximum number of plots is limited to 25 by default; a user can change the this limitation in the Settings window.

Download button in Plotly.js graph unfunctions

The download button in the Plotly.js mode bar, which appears at the top right corner when the cursor is on the graph, does not function. Read GitHub Issue #1 for more details.

Unsupported text encodings for not-in-editor documents

When a preview whose source editor has been closed is reloaded, the extension tries to load the file contents using the value for files.encoding setting ID as the text encoding. The current implementation does not support several text encodings in this situation and defaults to UTF-8 in these cases. See GitHub issue fujidana/vscode-spec-command#6 for more details. In most cases data files will consist of ASCII characters only. Then, it is safely loaded as UTF-8 and the problem does not arise.

Release Notes

See CHANGELOG.md.

Tips

Preview delimited text not generated by spec

The spec-data parser treats lines of delimited number that follow a #L column label line as an numeric array. In other word, one may be able to make a graph for delimited text when one just adds a #L line at the top of the content.

The parser is made torelant. It accepts a tab character in addition to whitespaces as a delimiter and handles redundant delimiters (typically used for alignment) properly. One thing that should be noted is that, spec uses double whitespace as a delimiter of column labels (probably by reason of disticution from a single whitespace that may be included in a column label) and the extension follows this rule. When a tab character is used as a delimiter, a user do not care about this problem (double tab characters are unnecessary).

The following is a minimum example of the spec data format the extension can handle.

#L time [sec]  distance [m]
          0.0        -6.2e2
        100.0         9.1e2
        200.0         3.1e3

A user can test it by the following procedure:

Create a new window
Select "spec data" as its language mode
Copy the example above and paste it into the editor
Open Preview (Win/Linux: Ctrl+Shift+V, Mac: Cmd+Shift+V)

If one wants to draw graph from a set of numbers in a row (i.e., line, not a column), make VS code recognize the file as an MCA file.

Make spec output an MCA file

The following code is an example to output the data of an MCA device in spec. This assumes an MCA device that has 1024 data points of 32-bit unsigned integer is configured at #0 slot in spec.

# create a buffer
ulong array buffer[1024]

# copy MCA data to the buffer
mca_sget(0, buffer)

# output data in a row.
array_op("row_wise", buffer, 1)
array_dump("output.mca", buffer)

Each time array_dump() is executed, a new line consisting of 1024 integers is appended at the end of file.

Make spec automatically set the file extension

SPECD/standard.mac defines user_filecheck(s) funciton, which simply returns the input argument s. A User can override this function in order to insert a macro to massage or test the file name for newfile.

To let newfile add ".spec" as the file extension, define the following function in spec.

def user_filecheck(s) '{
    if (s == "null" || s == "/dev/null") {
        return s
    } else if (match(s, "^(.+/)?([^./]+)\$")) {
        # add ".spec" to filename if a user does not specify the file extension
        return sprintf("%s.spec", s)
    } else {
        # simply return the provided filename if a user specifies the file extension
        return s
    }
}'

spec data

fujidana