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 extension does not associate the file extensions such as .csv, tsv, or dat with and language ID by the following reasons:
    • The extension can not determine from the file extension which direction (column-wise or row-wise) an array should be extracted from a table.
    • The extension do not intend to support all possible features for general CSV files. The main feature is drawing a graph and thus files consisting of number only are targeted.
  • 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.
  • Note that the spec software does not specify a file extension for the data format. Use of .spec for spec data file is just the preference of the extension author.
• 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 default file associations (relations between language identifier and file extensions) are set as listed above, a user can customize them using files.associations setting. 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 (as of v.1.7.0 both scroll-preview-with-editor and scroll-editor-with-preview are supported.)

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.

Customization of Graph Appearances

note: spec-data.preview.plot.traceTemplate was deprecated and the way to customize the templates was changed at v1.7.0. Read the following to migrate the settings.

To the extension author's knowledge, Plotly.js does not provide a simple way to support so-called dark mode. Therefore, the extension has prepared its own Plotly.js templates for the four color themes of VS Code and switches them according to the active color theme of VS Code. These template objects can be found at src/previewTemplates.ts in the GitHub repository.

A user can modify the appearance of graphs by overriding these templates via the spec-data.preview.plot.traceTemplate and spec-data.preview.plot.layoutTemplate settings. Both the settings shall be a JSON object having at most 4 keys, "light", "dark", "highContrast", and "highContrastLight". The template shall be defined with respect to each color theme.

The former setting, spec-data.preview.plot.traceTemplate, is for customization of trace appearances such as a line color. The value corresponding to each color theme shall be an array of template objects for scatter plots. The templates are applied cyclically to multiple traces. With the following example, the extension draws traces in red and blue altenatively only when light color theme is selected.

{
  "spec-data.preview.plot.traceTemplate": {
    "light": [
        { "marker": { "color": "#f00" }, "line": { "color": "#f00" } },
        { "marker": { "color": "#00f" }, "line": { "color": "#00f" } }
    ]
  }
}

One can find parameter names typically used for customization in the extension's default template file, src/previewTemplates.ts. For more comprehensive list of trace template parameters, see Plotly.com - Scatter traces in JavaScript.

The latter setting, spec-data.preview.plot.layoutTemplate, is for customization of layout appearances such as a background color. Unlike the former setting, the value for the color theme key in this setting is an object (IOW, dictionary), not an array. One can find parameter names typically used for customization in the extension's template file, src/previewTemplates.ts. For more comprehensive list of layout template parameters, see Plotly.com - Layout in JavaScript.

When an empty array and object are passed for these settings, they overwrite the extension's settings and thus, graphs are drawn with vanilla Plotly.js's (i.e., not the extension's) template. For example, with the following settings the graph is drawn in the default manner of Plotly.js, with white background color even in dark mode.

{
    "spec-data.preview.plot.traceTemplate": { "dark": [] },
    "spec-data.preview.plot.layoutTemplate": { "dark": {} }
}

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. When data in a file is separated in several blocks (depending on the file format but) typically with two or more empty lines, the extension creates a page consisting of multiple graphs. While Plotly.js looks performant as an interactive and nice-looking graph generator, to render a preview consisting of a large number of graphs cosumues both CPU and memory resources. For this reason, the maximum number of graphs 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 such cases. See GitHub issue fujidana/vscode-spec-command#6 (another extension) for more details.

Release Notes

See CHANGELOG.md.

Tips

File associations using the file contents

In addition to a file extension and file pattter, VS Code refers to the first line of a file in order to associate the file with a language (IOW, editor mode). A text file starting with # mode: csv-row and # mode: csv-column is automatically associated with csv-row and csv-column, respectively.

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
    }
}'