spec Data File Extension for Visual Studio Code

The extension enables a user to browse spreadsheet-like data in a graph with Visual Studio Code. The graph feature can be controlled in a similar way with a built-in Markdown Preview feature. For example, spec data:Open Preview command (Win/Linux: Ctrl+Shift+V, Mac: Cmd+Shift+V) is available when a supported file is open.

The data file formats the exension supports are as follows:

• CSV file (ID: csv-column, csv-row): CSV (character-separated values) files.
  • A pair of columns in a csv-column file and that of rows in a csv-row file can be graphically plotted.
  • All cells must be numeric; string may appear only in a header line that starts with a hash character (#).
  • A delimiter may be either a whitespace, tab, or comma, and is auto-detected.
  • The IDs are not associated with any file extensions by default because it can not be determined from a file extension which direction (column-wise or row-wise) an array should be extracted from a table.
  • A data file exported by ESRF's spec macro, BLISS / mca.mac, is also covered in csv-row.
• spec standard data file (ID: spec-data, extension: .spec): files the spec software outputs during various scan commands.
• fit2d chiplot file format (ID: chiplot, extension: .chi): a text file format in which fit2d software imports and exports one-dimensional dataset such as scattering profiles.
• DppMCA spectra data file format (ID: dppmca, extension: .mca): DppMCA is DP5 Digital Pulse Prosessor Display & Acquisition Software for Multichannel Analyzers, developed by Amptek.

While the extension associates spec-data file with .spec file by default, spec does not specify a file extension for the data format. Also, the extension does not associate csv-row or csv-column file with any file extensions commonly used for CSV files (.csv, tsv, or dat). However, a user can set and modify the association between a language identifier and file extensions (or blob pattern) by oneself. Read Language Support in Visual Studio Code (official document of VS Code) for further details.

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 (spec-data and dppmca only)
  • 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 (spec-data and dppmca only)
• Preview
  • motor positions just before a scan in a table view (spec-data only)
  • 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 works; scroll-editor-from-preview does not.)

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

Make spec output a row-wise CSV 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 (ulong) type 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.csv", 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
    }
}'